<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Setting up Table Prefixes : DataMapper ORM - User Guide</title>

<link rel="shortcut icon" type="image/png" href="../images/favicon.png" />
<link rel="stylesheet" type="text/css" media="all" href="../css/userguide.css" />
<link rel="alternate" type="application/rss+xml" title="Datamapper ORM Updates Feed" href="/rss.xml" />

<meta http-equiv="expires" content="-1" />
<meta http-equiv= 'pragma' content="no-cache" />
<meta name="robots" content="all" />

</head>

<body>

<!-- START NAVIGATION -->
<div id="nav"><div id="nav_inner"></div></div>
<div id="nav2"><a name="top">&nbsp;</a><a id="nav_toggle" href="#"><img src="../images/nav_toggle_darker.jpg" width="154" height="43" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
<div id="masthead">
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td><h1>DataMapper ORM</h1></td>
<td id="breadcrumb_right"><a href="toc.html">Table of Contents Page</a></td>
</tr>
</table>
</div>
<!-- END NAVIGATION -->

<!-- START BREADCRUMB -->
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td id="breadcrumb">
<a href="/">Datamapper ORM Home</a> &nbsp;&#8250;&nbsp;
<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
Setting up Table Prefixes
</td>
</tr>

</table>
<!-- END BREADCRUMB -->

<br clear="all" />


<!-- START CONTENT -->
<div id="content">


<h1>Setting up Table Prefixes</h1>

<p>The final step of the <a href="installation.html">Installation Instructions</a> asks you to make sure you set the <dfn>dbprefix</dfn> in your database settings to an empty string. The reason for this is because DataMapper has its own way of managing prefixing, giving some added flexibility as well.</p>

<p>If you don't plan on using prefixes, go right ahead and skip to the <a href="relationtypes.html">Relationship Types</a> section.</p>

<h2>Prefix Settings</h2>

<p>There's a few ways you can define your prefixes, with the use of the <var><i>$prefix</i></var> and <var><i>$join_prefix</i></var> class variables.</p>

<ul>
	<li><var><i>$prefix</i></var> - If set, will require all tables (both normal and joining tables) to have this prefix.</li>
	<li><var><i>$join_prefix</i></var> - If set, will require all joining tables to have this prefix (overrides <var><i>$prefix</i></var>).</li>
</ul>

<p>To make all your DataMapper models use the same prefixes, I recommend setting the prefixes in the <a href="config.html">DataMapper config</a>, rather than setting the same prefixes in all of them.  If you do this, you can still override the prefix for individual models by setting the prefix within them.</p>

<h2>Prefix Only</h2>

<p>Let's go with the assumption that we've set our prefix up like so, and it applies to <strong>all</strong> of our models:</p>

<pre>
<kbd>var </kbd><var><i>$prefix</i> </var><kbd>= </kbd><dfn>"ci_"</dfn><kbd>;
var </kbd><var><i>$join_prefix</i> </var><kbd>= </kbd><dfn>""</dfn><kbd>;</kbd>
</pre>

<p>Using the first group of tables from the <a href="database.html">Database Tables</a> section, those being <strong>countries</strong>, <strong>countries_users</strong> and <strong>users</strong>, this is how they would be changed to work with the above set prefix:</p>

<h3>ci_countries</h3>
<table cellpadding="0" cellspacing="1" border="0" style="width:25%" class="tableborder">
<tr>
	<th>id</th>
	<th>code</th>
	<th>name</th>
</tr>
<tr>
	<td>12</td>
	<td>AM</td>
	<td>Armenia</td>
</tr>
<tr>
	<td>13</td>
	<td>AW</td>
	<td>Aruba</td>
</tr>
<tr>
	<td>14</td>
	<td>AU</td>
	<td>Australia</td>
</tr>
<tr>
	<td>15</td>
	<td>AT</td>
	<td>Austria</td>
</tr>
</table>

<h3>ci_countries_users</h3>
<table cellpadding="0" cellspacing="1" border="0" style="width:20%" class="tableborder">
<tr>
	<th>id</th>
	<th>country_id</th>
	<th>user_id</th>
</tr>
<tr>
	<td>1</td>
	<td>14</td>
	<td>7</td>
</tr>
<tr>
	<td>1</td>
	<td>12</td>
	<td>8</td>
</tr>
</table>

<h3>ci_users</h3>
<table cellpadding="0" cellspacing="1" border="0" style="width:25%" class="tableborder">
<tr>
	<th>id</th>
	<th>username</th>
	<th>password</th>
	<th>email</th>

</tr>
<tr>
	<td>7</td>
	<td>Foo</td>
	<td>ec773c1da6f96b0265d76fa0a53db697e66a8eea</td>
	<td>foo@bar.com</td>
</tr>
<tr>
	<td>8</td>
	<td>Baz</td>
	<td>383f27f548397ea123ec444505ef4c7cd993dbf6</td>
	<td>baz@qux.com</td>
</tr>
</table>

<p>You'll notice that only the table names were affected, including the joining table's name, and that prefixing has no affect on the field names.</p>

<h2>Both Prefixes</h2>

<p>Let's change our prefixes so we're setting a different prefix for our joining tables:</p>

<pre>
<kbd>var </kbd><var><i>$prefix</i> </var><kbd>= </kbd><dfn>"normal_"</dfn><kbd>;
var </kbd><var><i>$join_prefix</i> </var><kbd>= </kbd><dfn>"join_"</dfn><kbd>;</kbd>
</pre>

<h3>normal_countries</h3>
<table cellpadding="0" cellspacing="1" border="0" style="width:25%" class="tableborder">
<tr>
	<th>id</th>
	<th>code</th>
	<th>name</th>
</tr>
<tr>
	<td>12</td>
	<td>AM</td>
	<td>Armenia</td>
</tr>
<tr>
	<td>13</td>
	<td>AW</td>
	<td>Aruba</td>
</tr>
<tr>
	<td>14</td>
	<td>AU</td>
	<td>Australia</td>
</tr>
<tr>
	<td>15</td>
	<td>AT</td>
	<td>Austria</td>
</tr>
</table>

<h3>join_countries_users</h3>
<table cellpadding="0" cellspacing="1" border="0" style="width:20%" class="tableborder">
<tr>
	<th>id</th>
	<th>country_id</th>
	<th>user_id</th>
</tr>
<tr>
	<td>1</td>
	<td>14</td>
	<td>7</td>
</tr>
<tr>
	<td>1</td>
	<td>12</td>
	<td>8</td>
</tr>
</table>

<h3>normal_users</h3>
<table cellpadding="0" cellspacing="1" border="0" style="width:25%" class="tableborder">
<tr>
	<th>id</th>
	<th>username</th>
	<th>password</th>
	<th>email</th>

</tr>
<tr>
	<td>7</td>
	<td>Foo</td>
	<td>ec773c1da6f96b0265d76fa0a53db697e66a8eea</td>
	<td>foo@bar.com</td>
</tr>
<tr>
	<td>8</td>
	<td>Baz</td>
	<td>383f27f548397ea123ec444505ef4c7cd993dbf6</td>
	<td>baz@qux.com</td>
</tr>
</table>


<h2>Join Prefix Only</h2>
<p>Now let's change it so we're only prefixing our joining table's, leaving our normal tables without a prefix:</p>

<pre>
<kbd>var </kbd><var><i>$prefix</i> </var><kbd>= </kbd><dfn>""</dfn><kbd>;
var </kbd><var><i>$join_prefix</i> </var><kbd>= </kbd><dfn>"join_"</dfn><kbd>;</kbd>
</pre>


<h3>countries</h3>
<table cellpadding="0" cellspacing="1" border="0" style="width:25%" class="tableborder">
<tr>
	<th>id</th>
	<th>code</th>
	<th>name</th>
</tr>
<tr>
	<td>12</td>
	<td>AM</td>
	<td>Armenia</td>
</tr>
<tr>
	<td>13</td>
	<td>AW</td>
	<td>Aruba</td>
</tr>
<tr>
	<td>14</td>
	<td>AU</td>
	<td>Australia</td>
</tr>
<tr>
	<td>15</td>
	<td>AT</td>
	<td>Austria</td>
</tr>
</table>

<h3>join_countries_users</h3>
<table cellpadding="0" cellspacing="1" border="0" style="width:20%" class="tableborder">
<tr>
	<th>id</th>
	<th>country_id</th>
	<th>user_id</th>
</tr>
<tr>
	<td>1</td>
	<td>14</td>
	<td>7</td>
</tr>
<tr>
	<td>1</td>
	<td>12</td>
	<td>8</td>
</tr>
</table>

<h3>users</h3>
<table cellpadding="0" cellspacing="1" border="0" style="width:25%" class="tableborder">
<tr>
	<th>id</th>
	<th>username</th>
	<th>password</th>
	<th>email</th>

</tr>
<tr>
	<td>7</td>
	<td>Foo</td>
	<td>ec773c1da6f96b0265d76fa0a53db697e66a8eea</td>
	<td>foo@bar.com</td>
</tr>
<tr>
	<td>8</td>
	<td>Baz</td>
	<td>383f27f548397ea123ec444505ef4c7cd993dbf6</td>
	<td>baz@qux.com</td>
</tr>
</table>


<h2>Combination Prefix</h2>

<p>As mentioned earlier, you can set specific prefixes for individual models.  If we had the following prefixes setup to apply to <strong>all</strong> of our models, by setting it in the <a href="config.html">DataMapper config</a>:</p>

<pre>
<kbd>var </kbd><var><i>$prefix</i> </var><kbd>= </kbd><dfn>"normal_"</dfn><kbd>;
var </kbd><var><i>$join_prefix</i> </var><kbd>= </kbd><dfn>"join_"</dfn><kbd>;</kbd>
</pre>

<p>And then had the following in our <strong>users</strong> model:</p>

<pre>
<kbd>var </kbd><var><i>$prefix</i> </var><kbd>= </kbd><dfn>"special_"</dfn><kbd>;
</pre>

<p class="important"><strong><em>Important:</em></strong> All joining tables must use the same prefix, so you should not override the <strong>$join_prefix</strong> with a different value if it is already set.</p>

<p>The tables would end up as:</p>

<h3>normal_countries</h3>
<table cellpadding="0" cellspacing="1" border="0" style="width:25%" class="tableborder">
<tr>
	<th>id</th>
	<th>code</th>
	<th>name</th>
</tr>
<tr>
	<td>12</td>
	<td>AM</td>
	<td>Armenia</td>
</tr>
<tr>
	<td>13</td>
	<td>AW</td>
	<td>Aruba</td>
</tr>
<tr>
	<td>14</td>
	<td>AU</td>
	<td>Australia</td>
</tr>
<tr>
	<td>15</td>
	<td>AT</td>
	<td>Austria</td>
</tr>
</table>

<h3>join_countries_users</h3>
<table cellpadding="0" cellspacing="1" border="0" style="width:20%" class="tableborder">
<tr>
	<th>id</th>
	<th>country_id</th>
	<th>user_id</th>
</tr>
<tr>
	<td>1</td>
	<td>14</td>
	<td>7</td>
</tr>
<tr>
	<td>1</td>
	<td>12</td>
	<td>8</td>
</tr>
</table>

<h3>special_users</h3>
<table cellpadding="0" cellspacing="1" border="0" style="width:25%" class="tableborder">
<tr>
	<th>id</th>
	<th>username</th>
	<th>password</th>
	<th>email</th>

</tr>
<tr>
	<td>7</td>
	<td>Foo</td>
	<td>ec773c1da6f96b0265d76fa0a53db697e66a8eea</td>
	<td>foo@bar.com</td>
</tr>
<tr>
	<td>8</td>
	<td>Baz</td>
	<td>383f27f548397ea123ec444505ef4c7cd993dbf6</td>
	<td>baz@qux.com</td>
</tr>
</table>


</div>
<!-- END CONTENT -->


<div id="footer">
<p>
Next Topic:&nbsp;&nbsp;<a href="models.html">Database Models</a>
&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
Next Topic:&nbsp;&nbsp;<a href="relationtypes.html">Relationship Types</a>
</p>
<div id="copyrights">
<p><a href="/">Datamapper ORM</a> &nbsp;&middot;&nbsp; Copyright &copy; 2010-2011 &nbsp;&middot;&nbsp; Harro "WanWizard" Verton</p>
<p><a href="license.html">Other License Information</a></p>
</div>
</div>

<script type="text/javascript" src="../js/mootools.js"></script>
<script type="text/javascript" src="../js/menu.js"></script>
<script type="text/javascript">
<!--
	window.addEvent('domready', function() {

		// Create Menu
		var menu = new Menu({
			basepath: '../',
			pagespath: ''
		});

	});
//-->
</script>
</body>
</html>
